Quickstart
KML/KMZ
KML Reflector
Region Based KML
Legends

Quickstart

To get started with GeoServer and Google Earth right away simply type a wms / kml url into your web browser and open the result with Google Earth.

An alternative is to add the data directly in Google Earth via a Network Link:

When adding the network link directly in Google Earth it is possible to set a number of parameters which control how the data is handled by Google Earth. Here are some good defaults:

localhost The examples in this tutorial assume GeoServer is installed on the same host that Google Earth is running on. If this is not the case simply replace "localhost:8080" with the hostname:port of the host running GeoServer.

View-Based Refresh With View-Based Refresh the bounding box parameter (bbox) is appended to Link automatically by Google Earth. So you don't need to attach the bounding box parameter to a request if you are using view-based refresh (which is usually what you want). If you however only wish to use a Time-Based Refresh then you must manually specify the bounding box as part of the Link. For example: http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states*bbox=-180,-90,180,90

KML and KMZ Output

GeoServer supports both KML and KMZ output for WMS requests so data can be served up to Google Eearth.

KML is vector output, and KMZ (KML Zipped) will contain raster images of the data instead of vector data.

To return KML in a WMS getMap request, just set the "format" value to application/vnd.google-earth.kml+XML. For example:
http://localhost:8080/geoserver//wms?service=WMS&request=GetMap&format=application/vnd.google-earth.kml+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90

To return KMZ in a WMS getMap request, just set the "format" value to application/vnd.google-earth.kmz. For example:
http://localhost:8080/geoserver//wms?service=WMS&request=GetMap&format=application/vnd.google-earth.kmz+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90

Vector vs. Raster

Vector data looks the best and is the most detailed at all zoom levels, but it can be quite big and cumbersome if the dataset is large. In that case, it is preferred to use raster images of the data instead (like a normal PNG WMS map request). When you ask for KMZ output, you can pass in the KMSCORE value as a parameter, and the server will determine whether it gives you KML (vector) or KMZ (raster) results.

Quick Use http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&KMSCORE=KMSCORE=30

Geoserver is smart enough to make the call between vector and raster output: there is a definite point where one will be larger than the other, depending on how much data is queried.
But we left it so the user can specify the threshold of where to draw the line between using vector output or raster output. This threshold value is the KMScore parameter.

The KMScore parameter is an integer between 0 and 100. It is an exponential value, meaning that the higher the KMScore value, the more features are required to return a raster output. Here are some example values:

Here is the formula used to determine the feature threshold:
Number of features = 10^(kmscore/15)

The server is set at a default KMScore value of 40 (464 features).

The same KMScore value is used on each layer, but each layer determines whether or not it has too many features to break the threshold, so some layers might be KML, and others might be KMZ.

Attribution

It is possible to return full attribution on the data in the form of a description on the placemark values of each feature. By default it is turned on, but you can turn full attribution off by passing in the KMATTR parameter with the value "false".

Turn off Full Attribution http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&KMATTR=false

KML Reflector

Have long and confusing WMS requests got you down? Do you not care what the parameters are and you just want a map back? Then the KML Reflector is for you!

We've taken out the hard part of WMS requests (they aren't that hard, but still one more thing you have to learn) and take the liberty of filling in all the parameters for you. Of course, if you supply any of the parameters in the URL, they will be taken over our supplied defaults.

To call the WMS reflector, you just need to point to your server location and pass in one parameter: 'layers'.

KML Reflector http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states

So instead of a request to "<server>/geoserver/wms?parameters", you send the request to "<server>/geoserver/wms/kml_reflect?layers=myLayer".
You just have to list the layers you want returned after the 'layers=' parameter, and separate each layer name with a comma. You might need to prefix each layer with its namespace value.

To test this out, create a new network link, like above, but change the URL to http://localhost:8080/geoserver/wms/kml_reflect?layers=states
The request will be sent to the KML Reflector and it will generate a KML file that contains a NetworkLink for each layer you passed in, with all of the default values filled in. These value are:

• KMScore
• KMAttr
• Version
• Width
• Height
• SRS

The default image width and height are both 1024 pixels.

The network link that is returned will also be configured for 'view-based refresh' with a delay of 3 seconds. So an automatic viewing bounding box will be submitted and you won't need to add your own.

Using the KML Reflector is by far the easiest way to serve data up to Google Earth from GeoServer.

Region Based KML

KML supports the notion of regions in which the map or view area is divided up into sections. This allows Google Earth to refresh/request only particular sections of the map when say the view area changes, which is much more efficient then requesting/refreshing all the data over again. This is similar in notion to the concept of tiling. Similar to tiles, regions fall into a hierarchy in which one region is made up of a number of smaller regions.

To instruct GeoServer to return region based kml simply append the parameter superoverlay=true to a kml request. For example:
http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&superoverlay=true

As you zoom into particular portions of the map you will notice that only those regions that fall within the camera view area are refreshed. This form of region based kml has a number of benefits. The first is described above in that it allows Google Earth to only re-request portions of data when the view changes. Which for large datasets can lead to a major performance improvement.

Tile Caching

The second benefit of using region based kml has to do with tile caching. GeoServer returns KML regions that are consistent with the WMS Tiling Specification which means that Google Earth will request the same regions that a tiling WMS client will. So if you are using GeoServer with a tile caching server you will reap the same performance benefits!

To configure region based kml to be used in conjunction with TileCache:

1. Install TileCache, instructions here
2. Navigate the GeoServer web ui to http://localhost:8080/geoserver/config/server.do (Config->Server from the home page)
3. Set the Tile Cache parameter to the location of TileCache
   

You can set the TileCache parameter to an absolute location like "http://sigma.openplans.org/tilecache/tilecache.py?" or you can set it to a relative location like "tilecache/tilecache.py?". The latter will be interpreted as relative to the same host GeoServer is running on. Be sure that you have the latest version of TileCache installed, as there are a few incompatibilities in earlier versions.

KML Legends

Using a combination of the WMS GetLegendGraphic operation and KML overlays GeoServer supports legends. To add a legend simply append the legend=true parameter to the kml request. For example:
http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&legend=true

kml_tutorial.jpg (image/jpeg)
addNetworkLink.png (image/png)
addNetworkLink.png (image/png)
addNetworkLink.png (image/png)
newNetworkLink.png (image/png)
newNetworkLink.png (image/png)
browser.png (image/png)
tilecache.png (image/png)
tilecache.png (image/png)

Great work! Are the KML capabilities built into the latest 1.3.1beta release? Posted by at May 30, 2006 13:35

No, we'll get a preview for everyone to download soon. If you're really interested you can email Brent or Chris for a more beta preview. Posted by cholmes at May 30, 2006 18:05